Program Availabilities Endpoint
The Program Availabilities endpoint provides access to programming information for various online streaming providers like Amazon, Hulu etc., including their pricing and availability information. This dataset is also called Online Video Data (OVD) .
Once licensed, the programs (TMSIds) referenced in the catalogs will be available in the Programs endpoint as well. And information about the streaming provider will be available on the Stations endpoint.
Program Availabilities provide the most up-to-date information on online video availability and enables universal search along with other compelling consumer applications more quickly and reliably with one data feed rather than dealing with the complexity of accessing and validating data from multiple partners. The Gracenote consolidated video data is synchronized with the Gracenote Unique ID for ease of integration with most major industry datasets.
ProgramAvailabilities API and Example Responses
API:
http://on-api.gracenote.com/v3/ProgramAvailabilities
?updateId=[updateId value] &limit=[limit value] &api_key=[your-api-key]
Request Parameters
Important: Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
Example Requests
Return Program Availabilities for programAvailabilityId GNBBPAPA5BR8XF7.
Using the providerId 1356240784 will return the same results.
http://on-api.gracenote.com/v3/ProgramAvailabilities?updateId=0&limit=10&programAvailabilityId=GNBBPAPA5BR8XF7&api_key=123456789
Example Responses
See Program Availability XML examples
Data Structure and Relationships
The Program Availabilities XSD schema file is located here:
http://files.api.gracenote.com/xsd/on_update_programAvailabilities_3.22.xsd
The XPATH in the tables below is relative to: on/programAvailabilities/programAvailability
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| @availabilityId | Identifier for the program availability | GN3DGTJ7BCV2WPD |
| catalogName | Name of the streaming catalog | Amazon PV US |
| availableFromDateTime | Optional availability window start date | 2022-11-11T00:00:00Z |
| expiresAtDateTime | Optional availability window expiration date | 3333-01-01T00:00:00Z |
The availabilityId uniquely identifies a catalog + Gracenote TMSId + videoQuality (see Viewing Options below). Availability window dates/times may or may not be present, depending on the catalog and specific assets. Assets with availability window are only present in the API during the availability window - with the exception of programs typed Sports event, which can be present ahead of the stated availability window.
Identifiers and Deeplinks
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| ids/id | Identifier associated with the asset | EP013898090001, 8553064, amzn1.dv.gti.a1b50383-d60a-4296-a6bd-ae3013ca6c82:US |
| ids/id/@type | Identifier type | tmsId, rootId, prgSvcId, providerId |
| urls/url | URL associated with the asset | http://www.amazon.com/gp/product/B0B8NBP1WV |
| urls/url/@type | URL type | web, ios, android, android_tv, stb, tizen, webos |
The identifier section includes Gracenote and provider identifiers. Gracenote identifiers are: Program TMSId and rootId, as well as Source prgSvcId (identifies a catalog). For additional information on Gracenote identifiers, please refer to the corresponding section - Programs Endpoint or Sources Endpoint. Provider identifiers consist of at least an asset providerId but can also include other (e.g. season or series level) identifiers.
Multiple assets can be assigned the same Gracenote TMSId - but not vice versa i.e. each asset will only have one assigned TMSId.
Deep links of the type web are included for all catalogs. Deep links for other device types may or may not be included depending on the provider.
Viewing Options
The XPATH in the table below is relative to:
on/programAvailabilities/programAvailability/viewingOptions/viewingOption
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| license | Video asset acquisition/payment method | purchase, subscription, rental, authentication, free |
| price | Video asset purchase/rental price | 3.99 |
| price/@currency | Video asset price currency | USD, CAD, EUR, GBP, ... |
| videoQuality | Video asset video quality | SD, HD, HD+, UHD |
The Viewing Options are available for watchable assets (movies, episodes), but not for series.
Provider Data
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| providerData/datum/key | Video asset provider specific data key | createdAtDate, p_rating, colorspace, show_id, season_id, airtime, ovd_image_url |
| providerData/datum/value | Video asset provider specific data value | 2022-12-28 06:51:06 UTC, 18+, SDR, ... |
The provider data key/values are optional passthrough data from the provider, not edited by Gracenote except for keys being normalized against a CV. The availability and coverage of specific keys is provider-dependent and varies greatly - some keys are only available for single catalogs. For the list of provider data keys, please refer to the below Referenced CV Lists table.
Referenced CV Lists
The Supplemental Controlled Vocabulary (auto-download) provides more comprehensive descriptions and examples for Availability-related lists.
Data Attributes in the Program Availabilities Dataset
Consistent with audience popularity, the majority of content covered by the Program Availabilities dataset is comprised of high-quality long form content available on major streaming provider catalogs.
Short-form content (such as, previews, interviews, movie trailers, etc.), music videos, sports, instructional, and user-generated content are not currently covered by the Program Availabilities dataset.
Online videos can be available on a number of platforms and devices for end viewer consumption. Gracenote understands that partners use Gracenote data to power experiences on a wide variety of devices and provides links for the following platforms for available catalogs:
Playability by platform is subject to change. Mobile playability may vary by device.
Host Logo Types
The Program Availabilities delivers image references for individual host logos. Host logos are available in four types. You should download the host logos and resize them as needed for your specific application.
| Alpha Light | 1076x720 pixels, PNG, transparent background, suitable for light backgrounds. |
|---|---|
| Alpha Dark | 1076x720 pixels, PNG, transparent background, suitable for dark backgrounds. |
| Solid Light | 1076x720 pixels, PNG, solid white background, suitable for light backgrounds. |
| Solid Dark | 1076x720 pixels, PNG, solid black background, suitable for dark backgrounds. |
Alpha Light
Alpha Dark
Solid Light
Solid Dark
Entity Relationship Diagram
The ProgramAvailabilities endpoint works in conjunction with the Programs endpoint. The ProgramAvailabilities endpoint contains the links between TMSIds and provider asset identifiers, the Programs endpoint includes the actual metadata for all referenced TMSIds, including Series records for any referenced Episodes.
